/*
 *  Copyright 2009 Lucas Nazário dos Santos
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  
 *      http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package net.sourceforge.retriever.filter;

import net.sourceforge.retriever.fetcher.Resource;

/**
 * <p>
 * Filters are used to filter resources during the crawling process.
 * </p>
 * 
 * <p>
 * It has two moments. The first one happens before resources are fetched, when
 * they are nothing more than their URLs. In this stage, one can inspect the URL
 * and decided if it's worth crawling or not.
 * </p>
 * 
 * <p>
 * The other moment is used to filter resources after they are fetched. In this stage,
 * the resource contains not only the URL, but also some other useful information like
 * the content-type, the content, length, etc. Users can, during this step, filter 
 * resources by a bigger set of information.
 * </p>
 * 
 * <p>
 * Filtering can be useful in a lot of different contexts. Some applications are the
 * elimination of resources of certain type (eg. xml, doc, pdf), of resources with
 * URLs not matching some pattern, resources with a non-desirable content-type,
 * resources that are above some size, or even resources in which content doesn't contain
 * a set of keywords. Filters are specially beneficial when implementing focused or
 * topic-driven crawlers. 
 * </p>
 */
public interface Filter {


	/**
	 * Filter a resource before the fetching process, when it's only a URL.
	 * 
	 * @param url The URL used in the filter process.
	 * @return True if the URL was accepted and won't be filtered and false otherwise.
	 */
	boolean acceptBeforeFetch(final String url);

	/**
	 * Filter a resource after the fetching process, when it's much richer than a
	 * simple URL, holding information like content-type, the content itself, and so on. 
	 * 
	 * @param url The resource used in the filter process.
	 * @return True if the resource was accepted and won't be filtered and false otherwise.
	 */
	boolean acceptAfterFetch(final Resource resource);
}